Kandria Dialogue Format

This document describes the markup syntax used for dialogues in Kandria. The basis for this is Speechless. Please see its documentation first and foremost. Here we will only outline extensions and functions specific to Kandria.

One specific extension is the retrieval of language-specific strings (such as for items). In order to splice this into dialogue you can use the following:

{#@strings-tag}

Where strings-tag is the name of an entry in the strings.lisp file. Eg: {#@fi-nametag} would place Fi's name. Or {#@item:small-health-pack} would place the title of the small health pack item.

The instruction ! can execute a variety of commands when encountered:

• go Jump to a given label in the dialogue

• speed Change the text scrolling speed

• camera Control the camera:

  • shake Cause the screen to shake for a bit

  • move Move the camera to another location

  • zoom Change the camera's zoom level

  • roll Change the camera's roll angle

  • reset Reset the camera to the standard view

• move Move a character to another location

• setf Change the value of a game variable or parameter

• eval Evaluate arbitrary Lisp code expressions
  Particularly useful functions are:

  • activate activate a trigger

  • deactivate deactivate a trigger

  • complete complete a trigger successfully

  • fail fail a trigger

  • active-p returns T if the given triggers are all active

  • complete-p returns T if the given triggers are all completed successfully

  • failed-p returns T if the given triggers are all marked as failed

  • have returns T if the player has the given item in their inventory
    Eg: (have 'item:mushroom 10) returns T if the player has at least 10 mushrooms.

  • item-count returns the count of the given item the player has in their inventory.

  • store adds the given item to the player's inventory. Optionally specify the number of the item to give
    Eg: (store 'item:small-health-pack 5) Give the player five small health packs.

  • retrieve removes the given item from the player's inventory. Optionally specify the number of items to remove
    Eg: (retrieve 'item:quest-item) Remove the quest item from the player's inventory.

  • unit returns the entity with the given name
    Eg: (unit 'catherine) returns Catherine. This can be useful for more specific state management.

  • (setf location) sets the location of the given entity. A location may be another entity or another entity's name.
    Eg: (setf (location 'player) 'some-area)

  • spawn spawn an NPC or enemy in the world. Requires a location and entity type as arguments.
    Eg: (spawn 'player 'zombie) Spawn a zombie at the player's location.

  • status Show a status message. This is typically automated for most events, but might be useful in rare cases.
    Eg: (status "Something changed...")

  • move-to Make an entity move to a location.
    Eg: (move-to 'player 'catherine) Makes Catherine move to where the player currently is.

  • lead Make an entity lead another to a location.
    Eg: (lead 'player 'cave 'catherine) Makes Catherine lead the player to the cave marker.

  • follow Make an entity follow another.
    Eg: (follow 'player 'catherine) Makes Catherine follow the player around.

  • stop-following Stop leading or following and return to standard AI activities.
    Eg: (stop-following 'catherine) Makes Catherine stop following anywhere..

  • walk-n-talk Initiate a walk and talk sequence where dialogue is played as the player has control.
    Eg: (walk-n-talk 'my-interaction) Plays the interaction named my-interaction as a walk-n-talk dialogue. Note: you cannot use choices in such interactions, but everything else is available. Be mindful of line length, too.

  • interrupt-walk-n-talk Interrupt the walk-n-talk dialogue to show another dialogue temporarily.
    Eg: (interrupt-walk-n-talk "| Hey, wait!") Interrupt the current dialogue with this piece. Note: you need to manually deactivate the interruption again.
    Eg: (interrupt-walk-n-talk NIL) to deactivate the interruption.

  • var access and manipulate variables. The variable with the requested name that is closest on the binding stack is used. (see variables)
    Eg: (var 'foo) will return the value of foo
    Eg: (setf (var 'foo) 0) will set the value of foo to 0.

  • contained-p Checks whether a given type of entity is within a region.
    Eg: (contained-p 'wolf 'market) returns T if there's at least one wolf enemy within the chunk named market.

  • move Directly control movement of the character
    The following movements are possible: :left, :right, :jump, :drop, :stop.
    Eg: (move :left 'catherine)

  • stop Stop the direct movement or pathing of a character
    Eg: ``(stop 'catherine)

  • ensure-nearby Ensure that the characters are near a place and teleport them there if they're not yet there.
    Eg: (ensure-nearby 'market 'catherine 'fi)

  • reset Reset a quest, task, or trigger to its initial state. This will make it inactive again and reset all variables and descendant objects.
    Eg: (reset 'sq3-race)

  • reset* Reset a quest, task, or trigger but without touching its variable state.
    Eg: (reset* 'sq3-race)

Also see documentation on the quest system for information on how quests, tasks, and interactions are meant to be understood.

If you're worried about the use of Lisp code, see the Lisp crash course for a quick introduction and explanation.

Editor integration

Visual Studio Code

We created an extension to offer syntax highlighting in VSC. To use it, simply clone our extension into VSC's extensions folder. On Windows, that's %USERPROFILE%\.vscode\extensions\ and elsewhere that's ~/.vscode/extensions/.

The extension can be found here: https://github.com/shirakumo/markless-vsc

Once it has been cloned in, restart VSC, and it should automatically be activated. You can test this by opening any file with the .mess or .spess extension.

Emacs

The emacs package markless can be installed from melpa. To activate it after installing, simply add this to your config:

(autoload 'markless-mode "markless" "" t nil)
(add-to-list 'auto-mode-alist '("\\.mess\\'" . markless-mode))
(add-to-list 'auto-mode-alist '("\\.spess\\'" . markless-mode))

Alternatively you can find the source here: https://github.com/shirakumo/markless.el